home *** CD-ROM | disk | FTP | other *** search
/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / languages / dde / _pc / h / sprite < prev    next >
Encoding:
Text File  |  1992-04-30  |  19.9 KB  |  604 lines
  1. (*
  2.  * Title  : sprite.h
  3.  * Purpose: provide access to RISC OS sprite facilities
  4.  *          
  5.  *)
  6.  
  7. # ifndef __sprite_h
  8. # define __sprite_h
  9.  
  10. # ifndef __os_h
  11. # include "os.h"
  12. # endif
  13.  
  14. (* 
  15.  * This file contains functions for performing operations on sprites.
  16.  * For brevity only a brief description is given for each call. More details
  17.  * can be found in the Programmer's Reference manual under the section on
  18.  * Sprite SWIs.
  19.  *
  20.  *)
  21.  
  22.  
  23.  
  24. (******** Simple operations, use no sprite area, no name/sprite pointer ***)
  25.  
  26. const
  27.   sprite_nopalette  = 0;
  28.   sprite_haspalette = 1;
  29.  
  30. type sprite_palflag_ptr = ^sprite_palflag;
  31.      sprite_palflag = integer;
  32.  
  33. type sprite_factors_ptr = ^sprite_factors;
  34.      sprite_factors =
  35.        record
  36.          xmag, ymag, xdiv, ydiv : integer
  37.        end;
  38.  
  39. type sprite_pixtrans_ptr = ^sprite_pixtrans;
  40.      sprite_pixtrans = byte;
  41.  
  42.  
  43. (* ----------------------------- sprite_screensave -------------------------
  44.  * Save the current graphics window as a sprite file, with optional palette.
  45.  * Equivalent to *ScreenSave.
  46.  *
  47.  *)
  48. procedure sprite_screensave(filename : string;
  49.                 flag : sprite_palflag) : error; extern;
  50.  
  51. (* ---------------------------- sprite_screenload --------------------------
  52.  * Load a sprite file onto the screen. Equivalent to *ScreenLoad.
  53.  *
  54.  *)
  55. procedure sprite_screenload(filename : string) : error; extern;
  56.  
  57.  
  58. (****** Operations on either system/user area, no name/sprite pointer *****)
  59.  
  60. type sprite_area_ptr = ^sprite_area;
  61.      sprite_area =     (* Format of a sprite area control block *)
  62.        record
  63.          size : integer;
  64.          number : integer;
  65.          sproff : integer;
  66.          freeoff : integer
  67.        end;
  68.  
  69. type sprite_header_ptr = ^sprite_header;
  70.      sprite_header =   (* Format of a sprite header *)
  71.        record
  72.          next : integer;      (*  Offset to next sprite                *)
  73.          name : packed array[1..11] of char;
  74.                               (*  Sprite name                          *)
  75.          width : integer;     (*  Width in words-1      (0..639)       *)
  76.          height : integer;    (*  Height in scanlines-1 (0..255/511)   *)
  77.          lbit : integer;      (*  First bit used (left end of row)     *)
  78.          rbit : integer;      (*  Last bit used (right end of row)     *)
  79.          image : integer;     (*  Offset to sprite image               *)
  80.          mask : integer;      (*  Offset to transparency mask          *)
  81.          mode : integer       (*  Mode sprite was defined in           *)
  82.                               (*  Palette data optionally follows here *)
  83.                               (*  in memory                            *)
  84.        end;
  85.  
  86. const sprite_mainarea = sprite_area_ptr(0); (* Typed constants !!! *)
  87.  
  88. type sprite_ptr = pointer;
  89.  
  90.  
  91. (* ------------------------ sprite_area_initialise -------------------------
  92.  * Initialise an area of memory as a sprite area 
  93.  *
  94.  *)
  95. procedure sprite_area_initialise(area : sprite_area_ptr;
  96.                 size : integer); extern;
  97.  
  98. (* ----------------------- sprite_area_readinfo ----------------------------
  99.  * Read information from a sprite area control block
  100.  *
  101.  *)
  102. procedure sprite_area_readinfo(area : sprite_area_ptr;
  103.                 resultarea : sprite_area_ptr) : error; extern;
  104.  
  105. (* --------------------------- sprite_area_reinit --------------------------
  106.  * Reinitialise a sprite area.
  107.  * If system area, then equivalent to *SNew
  108.  *
  109.  *)
  110. procedure sprite_area_reinit(area : sprite_area_ptr) : error; extern;
  111.  
  112. (* --------------------------- sprite_area_load ----------------------------
  113.  * Load a sprite file into a sprite area.
  114.  * If system area, then equivalent to *SLoad
  115.  *
  116.  *)
  117. procedure sprite_area_load(area : sprite_area_ptr;
  118.                 filename : string) : error; extern;
  119.  
  120. (* ---------------------------- sprite_area_merge --------------------------
  121.  * Merge a sprite file with a sprite area.
  122.  * If system area, then equivalent to *SMerge
  123.  *
  124.  *)
  125. procedure sprite_area_merge(area : sprite_area_ptr;
  126.                 filename : string) : error; extern;
  127.  
  128. (* ---------------------------- sprite_area_save ---------------------------
  129.  * Saves a sprite area as a sprite file.
  130.  * If system area, then equivalent to *SSave
  131.  *
  132.  *)
  133. procedure sprite_area_save(area : sprite_area_ptr;
  134.                 filename : string) : error; extern;
  135.  
  136. (* ---------------------------- sprite_getname -----------------------------
  137.  * Return the name and length of name of the n'th sprite in a sprite area
  138.  * into a buffer.
  139.  *
  140.  *)
  141. procedure sprite_getname(area : sprite_area_ptr;
  142.                 buffer : pointer;
  143.                 var length : integer;
  144.                 index : integer) : error; extern;
  145.  
  146. (* ---------------------------- sprite_get ---------------------------------
  147.  * Copy a rectangle of screen delimited by the last pair of graphics cursor
  148.  * positions as a named sprite in a sprite area, optionally storing the
  149.  * palette with the sprite.
  150.  *
  151.  *)
  152. procedure sprite_get(area : sprite_area_ptr;
  153.                 name : string;
  154.                 flag : sprite_palflag) : error; extern;
  155.  
  156. (* ---------------------------- sprite_get_rp ------------------------------
  157.  * Copy a rectangle of screen delimited by the last pair of graphics cursor
  158.  * positions as a named sprite in a sprite area, optionally storing the
  159.  * palette with the sprite. Address of sprite returned in resultaddress.
  160.  *
  161.  *)
  162. procedure sprite_get_rp(area : sprite_area_ptr;
  163.                 name : string;
  164.                 flag : sprite_palflag;
  165.                 var resultaddress : sprite_ptr) : error; extern;
  166.  
  167. (* ---------------------------- sprite_get_given ---------------------------
  168.  * Copy a rectangle of screen delimited by the given pair of graphics
  169.  * coordinates as a named sprite in a sprite area, optionally storing the
  170.  * palette with the sprite.
  171.  *
  172.  *)
  173. procedure sprite_get_given(area : sprite_area_ptr;
  174.                 name : string;
  175.                 flag : sprite_palflag;
  176.                 x0, y0, x1, y1 : integer) : error; extern;
  177.  
  178. (* --------------------------- sprite_get_given_rp -------------------------
  179.  * Copy a rectangle of screen delimited by the given pair of graphics
  180.  * coordinates as a named sprite in a sprite area, optionally storing the
  181.  * palette with the sprite. Address of sprite returned in resultaddress.
  182.  *
  183.  *)
  184. procedure sprite_get_given_rp(area : sprite_area_ptr;
  185.                 name : string;
  186.                 flag : sprite_palflag;
  187.                 x0, y0, x1, y1 : integer;
  188.                 var resultaddress : sprite_ptr) : error; extern;
  189.  
  190. (* ------------------------------ sprite_create ----------------------------
  191.  * Create a named sprite in a sprite area of specified size and screen mode,
  192.  * optionally reserving space for palette data with the sprite.
  193.  *
  194.  *)
  195. procedure sprite_create(area : sprite_area_ptr;
  196.                 name : string;
  197.                 flag : sprite_palflag;
  198.                 width, height, mode : integer) : error; extern;
  199.  
  200. (* ------------------------------ sprite_create_rp -------------------------
  201.  * Create a named sprite in a sprite area of specified size and screen mode,
  202.  * optionally reserving space for palette data with the sprite.Address of
  203.  * sprite returned in resultaddress.
  204.  *
  205.  *)
  206. procedure sprite_create_rp(area : sprite_area_ptr;
  207.                 name : string;
  208.                 flag : sprite_palflag;
  209.                 width, height, mode : integer;
  210.                 var resultaddress : sprite_ptr) : error; extern;
  211.  
  212.  
  213. (*********** Operations on system/user area, name/sprite pointer **********)
  214.  
  215. const
  216.   sprite_id_name = 0;
  217.   sprite_id_addr = $74527053; (* 'Magic' number ("SpRt") to test against *)
  218.  
  219. type sprite_type_ptr = ^sprite_type;
  220.      sprite_type = integer;
  221.  
  222. type sprite_id_ptr = ^sprite_id;
  223.      sprite_id_tag = 0..1;
  224.      sprite_id =
  225.        record
  226.          s : record
  227.                case sprite_id_tag of
  228.                  (* Can use either name of sprite or address (faster) *)
  229.                  0 : (name : string);
  230.                  1 : (addr : sprite_ptr)
  231.              end;
  232.          (* User must tag the use of this structure manually *)
  233.          tag : sprite_type
  234.        end;
  235.  
  236.  
  237. (* ----------------------------- sprite_select -----------------------------
  238.  * Select the specified sprite for plotting using plot(0xed,x,y).
  239.  *
  240.  *)
  241. procedure sprite_select(area : sprite_area_ptr;
  242.                 id : sprite_id_ptr) : error; extern;
  243.  
  244. (* ----------------------------- sprite_select_rp --------------------------
  245.  * Select the specified sprite for plotting using plot(0xed,x,y). Address of
  246.  * sprite returned in resultaddress.
  247.  *
  248.  *)
  249. procedure sprite_select_rp(area : sprite_area_ptr;
  250.                 id : sprite_id_ptr;
  251.                 var resultaddress : sprite_ptr) : error; extern;
  252.  
  253. (* ----------------------------- sprite_delete -----------------------------
  254.  * Delete the specified sprite.
  255.  *
  256.  *)
  257. procedure sprite_delete(area : sprite_area_ptr;
  258.                 id : sprite_id_ptr) : error; extern;
  259.  
  260. (* ----------------------------- sprite_rename -----------------------------
  261.  * Rename the specified sprite within the same sprite area.
  262.  *
  263.  *)
  264. procedure sprite_rename(area : sprite_area_ptr;
  265.                 id : sprite_id_ptr;
  266.                 newname : string) : error; extern;
  267.  
  268. (* ----------------------------- sprite_copy -------------------------------
  269.  * Copy the specified sprite as another named sprite in the same sprite area.
  270.  *
  271.  *)
  272. procedure sprite_copy(area : sprite_area_ptr;
  273.                 id : sprite_id_ptr;
  274.                 copyname : string) : error; extern;
  275.  
  276. (* ----------------------------- sprite_put --------------------------------
  277.  * Plot the specified sprite using the given GCOL action.
  278.  *
  279.  *)
  280. procedure sprite_put(area : sprite_area_ptr;
  281.                 id : sprite_id_ptr;
  282.                 gcol : integer) : error; extern;
  283.  
  284. (* ----------------------------- sprite_put_given --------------------------
  285.  * Plot the specified sprite at (x,y) using the given GCOL action.
  286.  *
  287.  *)
  288. procedure sprite_put_given(area : sprite_area_ptr;
  289.                 id : sprite_id_ptr;
  290.                 gcol, x, y : integer) : error; extern;
  291.  
  292. (* --------------------------- sprite_put_scaled ---------------------------
  293.  * Plot the specified sprite at (x,y) using the given GCOL action, and scaled
  294.  * using the given scale factors.
  295.  *
  296.  *)
  297. procedure sprite_put_scaled(area : sprite_area_ptr;
  298.                 id : sprite_id_ptr;
  299.                 gcol, x, y : integer;
  300.                 factors : sprite_factors_ptr;
  301.                 pixtrans : sprite_pixtrans_ptr) : error; extern;
  302.  
  303. (* ---------------------------- sprite_put_greyscaled ----------------------
  304.  * Plot the specified sprite at (x,y) using the given GCOL action, and 
  305.  * greyscaled using the given scale factors.
  306.  *
  307.  *)
  308. procedure sprite_put_greyscaled(area : sprite_area_ptr;
  309.                 id : sprite_id_ptr;
  310.                 x, y : integer;
  311.                 factors : sprite_factors_ptr;
  312.                 pixtrans : sprite_pixtrans_ptr) : error; extern;
  313.  
  314. (* ----------------------------- sprite_put_mask ---------------------------
  315.  * Plot the specified sprite mask in the background colour.
  316.  *
  317.  *)
  318. procedure sprite_put_mask(area : sprite_area_ptr;
  319.                 id : sprite_id_ptr) : error; extern;
  320.  
  321. (* ----------------------------- sprite_put_mask_given ---------------------
  322.  * Plot the specified sprite mask at (x,y) in the background colour. 
  323.  *
  324.  *)
  325. procedure sprite_put_mask_given(area : sprite_area_ptr;
  326.                 id : sprite_id_ptr;
  327.                 x, y : integer) : error; extern;
  328.  
  329. (* --------------------------- sprite_put_mask_scaled ----------------------
  330.  * Plot the sprite mask at (x,y) scaled, using the background colour/action
  331.  *
  332.  *)
  333. procedure sprite_put_mask_scaled(area : sprite_area_ptr;
  334.                 id : sprite_id_ptr;
  335.                 x, y : integer;
  336.                 factors : sprite_factors_ptr) : error; extern;
  337.  
  338. (* ----------------------------- sprite_put_char_scaled --------------------
  339.  * Paint char scaled at (x,y)
  340.  *
  341.  *)
  342. procedure sprite_put_char_scaled(ch : char;
  343.                 x, y : integer;
  344.                 factors : sprite_factors_ptr) : error; extern;
  345.  
  346. (* ---------------------------- sprite_create_mask -------------------------
  347.  * Create a mask definition for the specified sprite.
  348.  *
  349.  *)
  350. procedure sprite_create_mask(area : sprite_area_ptr;
  351.                 id : sprite_id_ptr) : error; extern;
  352.  
  353. (* ---------------------------- sprite_remove_mask -------------------------
  354.  * Remove the mask definition from the specified sprite.
  355.  *
  356.  *)
  357. procedure sprite_remove_mask(area : sprite_area_ptr;
  358.                 id : sprite_id_ptr) : error; extern;
  359.  
  360. (* ---------------------------- sprite_insert_row --------------------------
  361.  * Insert a row into the specified sprite at the given row.
  362.  *
  363.  *)
  364. procedure sprite_insert_row(area : sprite_area_ptr;
  365.                 id : sprite_id_ptr;
  366.                 row : integer) : error; extern;
  367.  
  368. (* ---------------------------- sprite_delete_row --------------------------
  369.  * Delete the given row from the specified sprite.
  370.  *
  371.  *)
  372. procedure sprite_delete_row(area : sprite_area_ptr;
  373.                 id : sprite_id_ptr;
  374.                 row : integer) : error; extern;
  375.  
  376. (* ---------------------------- sprite_insert_column -----------------------
  377.  * Insert a column into the specified sprite at the given column. 
  378.  *
  379.  *)
  380. procedure sprite_insert_column(area : sprite_area_ptr;
  381.                 id : sprite_id_ptr;
  382.                 column : integer) : error; extern;
  383.  
  384. (* ---------------------------- sprite_delete_column -----------------------
  385.  * Delete the given column from the specified sprite.
  386.  *
  387.  *)
  388. procedure sprite_delete_column(area : sprite_area_ptr;
  389.                 id : sprite_id_ptr;
  390.                 column : integer) : error; extern;
  391.  
  392. (* ----------------------------- sprite_flip_x -----------------------------
  393.  * Flip the specified sprite about the x axis
  394.  *
  395.  *)
  396. procedure sprite_flip_x(area : sprite_area_ptr;
  397.                 id : sprite_id_ptr) : error; extern;
  398.  
  399. (* ----------------------------- sprite_flip_y -----------------------------
  400.  * Flip the specified sprite about the y axis
  401.  *
  402.  *)
  403. procedure sprite_flip_y(area : sprite_area_ptr;
  404.                 id : sprite_id_ptr) : error; extern;
  405.  
  406.  
  407. type sprite_info_ptr = ^sprite_info;
  408.      sprite_info =
  409.        record
  410.          width, height, mask, mode : integer
  411.        end;
  412.  
  413. (* -------------------------------- sprite_readsize ------------------------
  414.  * Read the size information for the specified sprite_id
  415.  *
  416.  *)
  417. procedure sprite_readsize(area : sprite_area_ptr;
  418.                 id : sprite_id_ptr;
  419.                 resultinfo : sprite_info_ptr) : error; extern;
  420.  
  421.  
  422. type sprite_colour_ptr = ^sprite_colour;
  423.      sprite_colour =
  424.        record
  425.          colour, tint : integer
  426.        end;
  427.  
  428. (* ----------------------------- sprite_readpixel --------------------------
  429.  * Read the colour of a given pixel in the specified sprite_id
  430.  *
  431.  *)
  432. procedure sprite_readpixel(area : sprite_area_ptr;
  433.                 id : sprite_id_ptr;
  434.                 x, y : integer;
  435.                 resultcolour : sprite_colour_ptr) : error; extern;
  436.  
  437. (* ----------------------------- sprite_writepixel -------------------------
  438.  * Write the colour of a given pixel in the specified sprite_id
  439.  *
  440.  *)
  441. procedure sprite_writepixel(area : sprite_area_ptr;
  442.                 id : sprite_id_ptr;
  443.                 x, y : integer;
  444.                 colour : sprite_colour_ptr) : error; extern;
  445.  
  446.  
  447. const
  448.   sprite_masktransparent = 0;
  449.   sprite_masksolid       = 1;
  450.  
  451. type sprite_maskstate_ptr = ^sprite_maskstate;
  452.      sprite_maskstate = integer;
  453.  
  454. (* ------------------------------- sprite_readmask -------------------------
  455.  * Read the state of a given pixel in the specified sprite mask
  456.  *
  457.  *)
  458. procedure sprite_readmask(area : sprite_area_ptr;
  459.         id : sprite_id_ptr;
  460.         x, y : integer;
  461.         var resultmaskstate : sprite_maskstate) : error; extern;
  462.  
  463. (* ------------------------------- sprite_writemask ------------------------
  464.  * Write the state of a given pixel in the specified sprite mask
  465.  *
  466.  *)
  467. procedure sprite_writemask(area : sprite_area_ptr;
  468.         id : sprite_id_ptr;
  469.         x, y : integer;
  470.         var resultmaskstate : sprite_maskstate) : error; extern;
  471.  
  472.  
  473. type sprite_state_ptr = ^sprite_state;
  474.      sprite_state =
  475.        record
  476.          r : array[0..3] of integer
  477.        end;
  478.  
  479. (* ----------------------------- sprite_restorestate -----------------------
  480.  * Restores the old state after one of the sprite redirection calls
  481.  *
  482.  *)
  483. procedure sprite_restorestate(state : sprite_state) : error; extern;
  484.  
  485.  
  486. (* ---------------------------- sprite_outputtosprite ----------------------
  487.  * Redirect VDU output to a sprite, saving old state 
  488.  *
  489.  *)
  490. procedure sprite_outputtosprite(area : sprite_area_ptr;
  491.                 id : sprite_id_ptr;
  492.                 save_area : pointer;
  493.                 state : sprite_state_ptr) : error; extern;
  494.  
  495. (* ----------------------- sprite_outputtomask -----------------------------
  496.  * Redirects output to a sprite's transparency mask, saving old state
  497.  *
  498.  *)
  499. procedure sprite_outputtomask(area : sprite_area_ptr;
  500.                 id : sprite_id_ptr;
  501.                 save_area : pointer;
  502.                 state : sprite_state_ptr) : error; extern;
  503.  
  504. (* --------------------------- sprite_outputtoscreen -----------------------
  505.  * Redirect output back to screen, saving old state
  506.  *
  507.  *)
  508. procedure sprite_outputtoscreen(save_area : pointer;
  509.                state : sprite_state_ptr) : error; extern;
  510.  
  511. (* --------------------------- sprite_sizeof_spritecontext -----------------
  512.  * Get size of save area needed to save sprite context.
  513.  *
  514.  *)
  515. procedure sprite_sizeof_spritecontext(area : sprite_area_ptr;
  516.                 id : sprite_id_ptr;
  517.                 var size : integer) : error; extern;
  518.  
  519. (* ------------------------- sprite_sizeof_screencontext -------------------
  520.  * Get size of save area needed to save screen context.
  521.  *
  522.  *)
  523. procedure sprite_sizeof_screencontext(
  524.                 var size : integer) : error; extern;
  525.  
  526. (* ------------------------ sprite_removewastage ---------------------------
  527.  * Removes left hand wastage from a sprite
  528.  *
  529.  *)
  530. procedure sprite_removewastage(area : sprite_area_ptr;
  531.                 id : sprite_id_ptr) : error; extern;
  532.  
  533.  
  534. (* new SWIs *)
  535.  
  536. (* ------------------------ sprite_change_size -----------------------------
  537.  * General insert/delete rows/columns operations
  538.  *
  539.  *)
  540. procedure sprite_change_size(area : sprite_area_ptr;
  541.                 id : sprite_id_ptr;
  542.                 rows : boolean;
  543.                 at, number : integer) : error; extern;
  544.  
  545. (* Typedefs and functions for rotating sprites. *)
  546.  
  547. type sprite_pgm_ptr = ^sprite_pgm;
  548.      sprite_pgm =
  549.        record
  550.          p0, p1, p2, p3 : array[0..1] of integer
  551.        end;
  552.  
  553. type sprite_transmat_ptr = ^sprite_transmat;
  554.      sprite_transmat = array[0..5] of integer;
  555.  
  556. type sprite_box_ptr = ^sprite_box;
  557.      sprite_box =
  558.        record
  559.          x0, y0, x1, y1 : integer
  560.        end;
  561.  
  562. (* ------------------------ sprite_put_mask_trans ---------------------
  563.  * Put a box from the mask in background colours through a transformation matrix
  564.  *
  565.  *)
  566. procedure sprite_put_mask_trans(area : sprite_area_ptr;
  567.                 id : sprite_id_ptr;
  568.                 matrix : sprite_transmat_ptr) : error; extern;
  569.  
  570. (* ------------------------ sprite_put_mask_pgm -----------------------
  571.  * Put a box from the mask in background colours to a parallelogram
  572.  *
  573.  *)
  574. procedure sprite_put_mask_pgm(area : sprite_area_ptr;
  575.                 id : sprite_id_ptr;
  576.                 box : sprite_box_ptr;
  577.                 pgm : sprite_pgm_ptr) : error; extern;
  578.  
  579. (* ------------------------ sprite_put_trans --------------------------
  580.  * Put a box from the sprite through a transformation matrix
  581.  *
  582.  *)
  583. procedure sprite_put_trans(area : sprite_area_ptr;
  584.                 id : sprite_id_ptr;
  585.                 gcol_action : integer;
  586.                 box : sprite_box_ptr;
  587.                 matrix : sprite_transmat_ptr;
  588.                 pixtrans : sprite_pixtrans_ptr) : error; extern;
  589.  
  590. (* ------------------------ sprite_put_pgm ----------------------------
  591.  * Put a box from the sprite to a parallelogram
  592.  *
  593.  *)
  594. procedure sprite_put_pgm(area : sprite_area_ptr;
  595.                 id : sprite_id_ptr;
  596.                 gcol_action : integer;
  597.                 box : sprite_box_ptr;
  598.                 pgm : sprite_pgm_ptr;
  599.                 pixtrans : sprite_pixtrans_ptr) : error; extern;
  600.  
  601. # endif
  602.  
  603. (* end of sprite.h *)
  604.